Introduction to Quarto

2024-08-21

Quarto basics

What is Quarto?

  • Renders plain text containing code
  • Code in multiple languages: R, Python, Julia, Observable
  • Multiple output formats: html, docx, tex, pdf

R code

What is Quarto?

  • Renders plain text containing code
  • Code in multiple languages: R, Python, Julia, Observable
  • Multiple output formats: html, docx, tex, pdf

Python code

What is Quarto?

  • Renders plain text containing code
  • Code in multiple languages: R, Python, Julia, Observable
  • Multiple output formats: html, docx, tex, pdf

Julia code

Why Quarto?

Literate programming

  • Compilable code embedded in narrative text
  • Text can be documentation or traditional report
  • Widely used in scientific computing esp. in data science
  • Facilitates open, reproducible research

How does Quarto work?

  • Create a YAML header (global options)
  • Write text in markdown
  • Add code blocks
  • Render the document to desired output format

Rendering

  • Depending on code language, an engine for generating dynamic reports is chosen (e.g. knitr)
  • Engine executes code to produce a markdown document that includes code and output
  • Pandoc (another engine) turns the markdown file into the final
  • All this gets done by the “Render” button

What do you need to get started?

  1. Quarto (download here)
  2. Authoring tool (RStudio, Jupyter Lab, VS Code, any text editor)
  • Quarto comes with RStudio
  • R package quarto provides some extra functionality

Anatomy of a Quarto document

YAML header

---
title: "Data Science for Industry assignment 1"
author: "Your name here"
format: html
editor: visual
execute:
  echo: true
---
  • Demarcated by three dashes (---) on either end
  • Note indentation
  • The basic syntax of YAML uses key-value pairs in the format key: value
  • https://quarto.org/docs/reference/formats/html.html

YAML header

---
title: "Introduction to Quarto"
date: "`r format(Sys.time(), '%d %B, %Y')`"
format: 
  revealjs:
      chalkboard: true
      scrollable: true
      theme: default
      footer: "STA5073Z Data Science for Industry"
      slide-number: true
      show-slide-number: print
      echo: true
---

Markdown text

  • Plain text formatted using markdown syntax
Italics with *asterisks* or _underscores_.
Bold, with **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~
  • Italics with asterisks or underscores.
  • Bold, with asterisks or underscores.
  • Combined emphasis with asterisks and underscores.
  • Strikethrough uses two tildes. Scratch this.

Markdown text

* Unordered list can use asterisks
- Or minuses
+ Or pluses
  • Unordered list can use asterisks
  • Or minuses
  • Or pluses

Markdown text

* Unordered list can use asterisks, minuses or pluses
  - But indentation matters
    + But indentation matters
  + Indentation matters
  • Unordered list can use asterisks, minuses or pluses
    • But indentation matters
      • But indentation matters
    • Indentation matters

Code

R Code:

```{r, echo = FALSE}
data(mtcars)
summary(mtcars$mpg)
```

Produces:

   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
  10.40   15.43   19.20   20.09   22.80   33.90 

Code

Chunk options as YAML with #|

```{r}
#| echo: false
data(mtcars)
summary(mtcars$mpg)
```

Produces:

   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
  10.40   15.43   19.20   20.09   22.80   33.90 

Code

R Code:

```{r, echo = FALSE}
data(mtcars)
summary(mtcars$mpg)
```

Syntax:

  • 3 ticks on either side followed by {} with some code
  • Ticks indicate start and end of code section
  • {r, options} is knitr syntax saying how R should read and display code

Figures

Inserting figures

![A caption](images/Seec.png)

A caption

Positioning figures

![](images/Seec.png){fig-align="left"}

Positioning figures

![](images/Seec.png){fig-align="center"}

Resizing figures

![](images/Seec.png){fig-align="center" width="75%"}

Subfigures

::: {#fig-git layout-ncol=3}
![Step 1](images/gitproj1.png){width="300px"}

![Step 2](images/gitproj2.png){width="300px"}

![Step 3](images/gitproj3.png){width="300px"}

Linking an R project with GitHub
:::

Subfigures

Step 1

Step 2

Step 3

Figure 1: Linking an R project with GitHub

Stacking figures

::: {.r-stack}
![](images/gitproj1.png){.fragment width="600"}

![](images/gitproj2.png){.fragment width="550"}

![](images/gitproj3.png){.fragment width="500"}
:::

Tables

Markdown Syntax

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Output

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

Diagrams

  • Quarto supports creating diagrams with Mermaid and Graphviz diagrams
  • flowcharts, sequence diagrams, state diagrams, Gantt charts, and more
  • Plain markdown-like text syntax
```{mermaid}
%%| echo: off
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

Diagrams

  • Quarto supports creating diagrams with Mermaid and Graphviz diagrams
  • flowcharts, sequence diagrams, state diagrams, Gantt charts, and more
  • Plain markdown-like text syntax
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

Math notation

This generates an equation like $X\sim N(\mu,\sigma^2)$ that appears inline

This generates an equation like \(E = mc^{2}\) that appears inline

Put more important equations like $$X\sim N(\mu,\sigma^2)$$ onto their own line

Put more important equations like \[E = mc^{2}\] onto their own line

Callout blocks

:::{.callout-tip}
There are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Tip

There are five types of callouts, including: note, tip, warning, caution, and important.

  • Callouts draw extra attention to certain concepts
  • Type changes colour and icon of the callout
  • Learn more on callouts here

Presentations

Overview

Quarto supports a variety of formats for creating presentations, including:

  • revealjs (HTML)
  • PowerPoint
  • Beamer (LaTeX/PDF)

These use the same markdown syntax as other documents, just adapt YAML and use #, ## to delineate slides.

HTML slides

---
title: "Quarto presentations"
author: "Me"
format: 
  revealjs:
      theme: default
---

## This is a slide

- Point 1
- Point 2

## Another slide

- More points
- More points

HTML slides

Powerpoint slides

---
title: "Quarto presentations"
author: "Me"
format: pptx
---

## This is a slide

- Point 1
- Point 2

## Another slide

- More points
- More points

Powerpoint slides

Powerpoint slides

---
title: "Quarto presentations"
author: "Me"
format:
  pptx:
    reference-doc: mytemplate.pptx
---

## This is a slide

- Point 1
- Point 2

## Another slide

- More points
- More points

Powerpoint slides

Websites

Overview

  • Quarto Websites are just HTML files
  • They share navigational elements and a common structure
  • Mainly implemented through the YAML

YAML

---
project:
  type: website

website:
  title: "A Quarto Website"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - addition.qmd
      - multiplication.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
---
  • Save as _quarto.yml
  • Render in terminal with quarto preview and quarto render
  • Let’s look the .qmd files making up the website

index.qmd

---
title: "Welcome!"
---

This is a Quarto website.

To learn more about Quarto websites visit <https://quarto.org/docs/websites>.

addition.qmd

---
title: "Adding numbers in R"
---

To add numbers in R use `+`

```{r}
1 + 1
```

multiplication.qmd

---
title: "Multiplying numbers in R"
---

To multiply numbers in R use `*`

```{r}
2 * 3
```

Final website

Sources and further resources